<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>percentile_ranks 聚合 | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'search-aggregations-metrics-percentile-rank-aggregation.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/search-aggregations-metrics-percentile-rank-aggregation.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/search-aggregations-metrics-percentile-rank-aggregation.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/search-aggregations-metrics-percentile-rank-aggregation.html" rel="nofollow" target="_blank">../en/search-aggregations-metrics-percentile-rank-aggregation.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch 权威指南 [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="search-aggregations.html">聚合</a></span>
»
<span class="breadcrumb-link"><a href="search-aggregations-metrics.html">度量聚合</a></span>
»
<span class="breadcrumb-node">percentile_ranks 聚合</span>
</div>
<div class="navheader">
<span class="prev">
<a href="search-aggregations-metrics-percentile-aggregation.html">« percentiles 聚合</a>
</span>
<span class="next">
<a href="search-aggregations-metrics-scripted-metric-aggregation.html">scripted_metric 聚合 »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="search-aggregations-metrics-percentile-rank-aggregation"></a>percentile_ranks 聚合
</h2>
</div></div></div>
<p>
一个 <code class="literal">multi-value</code>(多值) 度量聚合，计算从聚合文档中提取的数值的一个或多个百分位数排名。

这些值可以由给定的脚本生成，也可以从文档中的特定数值或 <a class="xref" href="histogram.html" title="histogram 数据类型" rel="nofollow">histogram 字段</a> 中提取。
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>
要了解有关百分位等级聚合<span class="remark">(percentile ranks aggregation)</span>的近似值和内存使用的建议，请参阅<a class="xref" href="search-aggregations-metrics-percentile-aggregation.html#search-aggregations-metrics-percentile-aggregation-approximation" title="Percentiles are (usually) approximate">百分位(通常)是近似值</a> 及 <a class="xref" href="search-aggregations-metrics-percentile-aggregation.html#search-aggregations-metrics-percentile-aggregation-compression" title="Compression">压缩</a>。
</p>
</div>
</div>
<p>
百分位数等级显示低于特定值的观察值的百分比。

例如，如果一个值大于或等于所有观察值中的95%,则称其处于第95百分位。
</p>
<p>
假设数据由网站加载时间组成。

可能有一个服务协议，内容是95%的页面加载在500毫秒内完成，99%的页面加载在600毫秒内完成。
</p>
<p>让我们看看代表加载时间(load_time)的百分比范围：</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET latency/_search
{
    "size": 0,
    "aggs" : {
        "load_time_ranks" : {
            "percentile_ranks" : {
                "field" : "load_time", <a id="CO200-1"></a><i class="conum" data-value="1"></i>
                "values" : [500, 600]
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/376.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO200-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>字段 <code class="literal">load_time</code> 必须是 numeric 类型的</p>
</td>
</tr>
</table>
</div>
<p>响应将如下所示：</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
    ...

   "aggregations": {
      "load_time_ranks": {
         "values" : {
            "500.0": 90.01,
            "600.0": 100.0
         }
      }
   }
}</pre>
</div>
<p>
根据这些信息，可以确定达到了99%的加载时间目标，但没有完全达到95%的加载时间目标<span class="remark">(在500毫秒内加载完成的只达到了90.01%)</span>
</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_keyed_response_2"></a>keyed 响应
</h3>
</div></div></div>
<p>
默认情况下，<code class="literal">keyed</code> 标志设置为 <code class="literal">true</code>，它将唯一的字符串键与每个桶相关联，并将范围作为哈希而不是数组返回。

将 <code class="literal">keyed</code> 标志设置为 <code class="literal">false</code> 将禁用此行为：
</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET latency/_search
{
    "size": 0,
    "aggs": {
        "load_time_ranks": {
            "percentile_ranks": {
                "field": "load_time",
                "values": [500, 600],
                "keyed": false
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/377.console"></div>
<p>响应：</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
    ...

    "aggregations": {
        "load_time_ranks": {
            "values": [
                {
                    "key": 500.0,
                    "value": 90.01
                },
                {
                    "key": 600.0,
                    "value": 100.0
                }
            ]
        }
    }
}</pre>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_script_11"></a>脚本
</h3>
</div></div></div>
<p>
百分位数等级度量支持脚本。

例如，如果加载时间是以毫秒为单位的，但我们希望以秒为单位提供值，我们可以使用一个脚本来进行动态转换：
</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET latency/_search
{
    "size": 0,
    "aggs" : {
        "load_time_ranks" : {
            "percentile_ranks" : {
                "values" : [500, 600],
                "script" : {
                    "lang": "painless",
                    "source": "doc['load_time'].value / params.timeUnit", <a id="CO201-1"></a><i class="conum" data-value="1"></i>
                    "params" : {
                        "timeUnit" : 1000   <a id="CO201-2"></a><i class="conum" data-value="2"></i>
                    }
                }
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/378.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO201-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>
参数 <code class="literal">field</code> 被替换为 <code class="literal">script</code>，它使用脚本来生成计算百分位等级的值
</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO201-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>像任何其他脚本一样，这里的脚本支持参数化输入</p>
</td>
</tr>
</table>
</div>
<p>
这将使用 <a class="xref" href="modules-scripting-painless.html" title="Painless scripting language" rel="nofollow">painless</a>(无痛) 脚本语言，没有脚本参数。

要使用存储的脚本，请使用以下语法：
</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET latency/_search
{
    "size": 0,
    "aggs" : {
        "load_time_ranks" : {
            "percentile_ranks" : {
                "values" : [500, 600],
                "script" : {
                    "id": "my_script",
                    "params": {
                        "field": "load_time"
                    }
                }
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/379.console"></div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_hdr_histogram_2"></a>HDR 直方图(Histogram)
</h3>
</div></div></div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>此设置公开了 HDR 直方图的内部实现，语法将来可能会改变。</p>
</div>
</div>
<p>
<a href="https://github.com/HdrHistogram/HdrHistogram" class="ulink" target="_top" rel="nofollow">HDR直方图</a> (High Dynamic Range Histogram, 高动态范围直方图)是一种替代实现，在计算延迟测量的百分位等级时非常有用，因为它比 t-digest 实现更快，但需要更大的内存。

这种实现保持固定的最坏情况百分比误差(指定为有效数字的数量)。

这意味着，如果在设置为 3 个有效数字的直方图中记录的数据值从 1 微秒到 1 小时(3,600,000,000微秒)，则对于 1 毫秒和 3.6 秒(或更好)的最大跟踪值(1小时)，它将保持 1 微秒的值分辨率。
</p>
<p>
通过在请求中指定参数 <code class="literal">method</code>，可以使用 HDR 直方图:
</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET latency/_search
{
    "size": 0,
    "aggs" : {
        "load_time_ranks" : {
            "percentile_ranks" : {
                "field" : "load_time",
                "values" : [500, 600],
                "hdr": { <a id="CO202-1"></a><i class="conum" data-value="1"></i>
                  "number_of_significant_value_digits" : 3 <a id="CO202-2"></a><i class="conum" data-value="2"></i>
                }
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/380.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO202-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>
<code class="literal">hdr</code> 对象表示应该使用HDR直方图来计算百分位数，并且可以在对象内部指定该算法的特定设置
</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO202-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>
<code class="literal">number_of_significant_value_digits</code> 指定直方图数值的分辨率，以有效位数表示
</p>
</td>
</tr>
</table>
</div>
<p>
HDR 直方图仅支持正值，如果向其传递负值，将会出错。

如果值的范围未知，使用HDR 直方图也不是一个好主意，因为这可能会导致很高的内存使用率。
</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_missing_value_10"></a>缺失的值
</h3>
</div></div></div>
<p>
参数 <code class="literal">missing</code> 定义应该如何处理有缺失值的文档。

默认情况下，它们会被忽略，但也可以将它们视为有一个(默认)值。
</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET latency/_search
{
    "size": 0,
    "aggs" : {
        "load_time_ranks" : {
            "percentile_ranks" : {
                "field" : "load_time",
                "values" : [500, 600],
                "missing": 10 <a id="CO203-1"></a><i class="conum" data-value="1"></i>
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/381.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO203-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>
<code class="literal">load_time</code> 字段中没有值的文档将与值为 <code class="literal">10</code> 的文档落入同一个桶。
</p>
</td>
</tr>
</table>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="search-aggregations-metrics-percentile-aggregation.html">« percentiles 聚合</a>
</span>
<span class="next">
<a href="search-aggregations-metrics-scripted-metric-aggregation.html">scripted_metric 聚合 »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>